CheckBoxCombo is a general-purpose Multi-select ComboBox User Control designed for Visual Basic. It differs from the conventional ComboBox behavior by allowing user to select one or more items from its drop-down list. CheckBoxCombo greately integrates the existing power of standard VB controls (ComboBox and ListBox) to provide its powerful features and can be easily integrated into any sort of Windows GUI project in VB.
The conventional ComboBox control in VB allows you to select only one item at a time from its drop-down list. It cannot be used in situations where you need to select more than one item at a time. For this particular purpose you should use a multi-choice enabled ListBox, which is all right, if you have enough space on your interface/form. But what if you have a very limited space to place the ListBox with dozens of items; may be closer to the bottom of your interface? CheckBoxCombo is a great replacement in such situations where you need to save the space on your UI (User Interface), with its great dynamic features.
CheckBoxCombo is also elegant in providing multiple inputs to SQL queries in database programming.
Further, CheckBoxCombo allows you to set any of its properties even at run-time, which is not even allowed by the traditional ComboBox control. One such property is [sorted], which you can dynamically set the sorting at run-time. This gives you a great flexibility in using the user control simply by overriding the design-time settings as you wish. CheckBoxCombo also exposes some methods to support less coding when working with it.
With its [OnListSearch] property, user can search and select any item in the list easily.
The user control greatly supports for modern visual styles since it integrates the existing VB controls which support visual styles.
The ActiveX version of CheckBoxCombo is fully compatible even with VBA, if you need to use CheckBoxCombo with Microsoft Office (32-bit) as well.
With CheckBoxCombo's professional features and familiarity in use due to nearly familiar syntax it provides, you will more feel it like a must to have control in your standard VB Toolbox.
| Property | Description | Example of use |
|---|---|---|
| DefaultText | The string in DefaultText property is displayed when nothing is selected in the drop-down list. You may keep this blank if you wish, but not recommended. This is a Get/Set property. The default is set as "---Select item(s)---". | CheckBoxCombo.DefaultText = "---Select items from the list---" |
| Text | The Text is only a Get property and it returns the text contained in the CheckBoxCombo control. The Text property now supports an optional parameter of type Boolean called DelimiterConcatIncluded which is set to True by default. When you want to get the selected items in the list, it is always recommended that you use SelItem property instead of Text. Note: If you have enabled the DelimiterConcat property, the Text property will contain the DelimiterConcat character concatenated with your original Delimiter. You can get the Text value excluding DelimiterConcat character by setting the DelimiterConcatIncluded to False. See the example and read the descriptions of (SelItem, SelItemData, and SelIndex) properties also. |
Dim var As String: var = CheckBoxCombo.Text Dim var As String: var = CheckBoxCombo.Text(False) 'excludes DelimiterConcat character |
| Delimiter | The Delimiter is a Get/Set property basically used as a seperator for the selected items in the drop-down list. You can set any character or combination, which is easy to read (Eg: |;~). If you enable DelimiterConcat property below (which is enabled by default), you need not to worry about delimiter collision. The default Delimiter is "," (Comma). Note: If you wish, you may keep the Delimiter blank by enabling the DelimiterConcat property, but never recommended. |
CheckBoxCombo.Delimiter = ";" 'selected items seperator |
| DelimiterConcat | The DelimiterConcat is a newly introduced property to avoid delimiter collision. Now the delimiter you set, can be internally concatenated with a non-printing ASCII character used as an Information Seperator, based on four options, [Chr(28) - File separator, Chr(29) - Group separator, Chr(30) - Record separator, Chr(31) - Unit separator]. The property is a Get/Set property with the default of "Chr(28) - File separator". You may set DelimiterConcat property to [None], if you think your Delimiter will not collid, but it is always recommended that you apply this property. Tip: If you have enabled this property, you should not worry about having your desired delimiter, since it is hardly possible to collid. When working with the code, you can simply get the delimiter by expression.Delimiter property and use without considering the DelimiterConcat property. And it is recommended that once you have set the DelimiterConcat in design-time, you should not try to change it. |
CheckBoxCombo.DelimiterConcat = [Chr(30) - Record separator] 'set the property |
| CBCUpdate | Generally, each time you select/unselect items in the list, CheckBoxCombo updates its selection state. This is almost OK, but only at the situations, where you need to select/unselect all/many items or to select items while adding/inserting them when you work with several hundrads, or several thousdands list items, the update process of CheckBoxCombo may take some considerable time. The CBCUpdate property is a special property introduced to eliminate such issues and get optimized results. The property is a Get/Set property based on True or False and is enabled by default. For stability reason, the property setting is only allowed at run-time. By setting this property to False, the update process of CheckBoxCombo can be avoided and do the lengthy selection work as explained, which gives extremly fast results. Upon completion of the work, the CBCUpdate property must be set to True, which restores its selection state and fires an event called CBCUpdateCompleted (See events section for CBCUpdateCompleted). Note: In many cases with small lists, you need not to use CBCUpdate settings. Therefore, use it ONLY when such need arises. If you disable CBCUpdate then you must restore it by enabling it after completion of the work, otherwise CheckBoxCombo state is not updated. When SelectAllOnRightClick property is enabled and you right-click on the drop-down list to select/unselect all items, the CBCUpdate status is automatically handled. |
CheckBoxCombo.CBCUpdate = False 'avoids CheckBoxCombo state update CheckBoxCombo.SelectAll 'selects all items in the lengthy list CheckBoxCombo.CBCUpdate = True 'restores the selection state |
| BackColor | You can set/return the BackColor of CheckBoxCombo using this property. | CheckBoxCombo.BackColor = vbWhite |
| ForeColor | This property sets/returns the ForeColor of the User Control. | CheckBoxCombo.ForeColor = vbGreen |
| Font | You can set/returns Font settings of CheckBoxCombo using this property. | CheckBoxCombo.Font = Thahoma CheckBoxCombo.Font.Bold = True CheckBoxCombo.Font.Size = 12 |
| Enable | This returns/sets Enabled status of the User Control based on True or False. | CheckBoxCombo.Enabled = False |
| ItemsToDisplay | This property sets/returns number of items to display in CheckBoxCombo when its drop-down list is shown. The value, 25 is set by default. If the number of items in the list go beyond this value, vertical scrollbar is added to the list. Note: Though this property does not restrict you setting the value, you should use this property wisely. It is always better to keep the default or less. |
CheckBoxCombo.ItemsToDisplay = CheckBoxCombo.ListCount 'dynamic and whole list is shown CheckBoxCombo.ItemsToDisplay = 10 'fixed |
| ItemData | The ItemData property returns/sets ItemData value (specific/extra number associated) of an item by a given index. It returns -1/false on failure in accessing an item. | Dim var As Long: var = CheckBoxCombo.ItemData(1) 'gets the ItemData value at Index 1 CheckBoxCombo.ItemData(5) = 6 'sets the ItemData value as 6 at the index 5 |
| LongestTextDisplayMode | This property determines how texts are displayed, when they are longer than the width of the CheckBoxCombo. This is a Get/Set property and has three options called [None, Scrolled, Autosized]. When the option, [Scrolled] is applied, horizontal scrollbar is dynamically added to the drop-down list, while the [Autosized] option dynamically expands the drop-down list when necessary. The property is set to [None] by default. | CheckBoxCombo.LongestTextDisplayMode = Autosized 'or CheckBoxCombo.LongestTextDisplayMode = 2 |
| ListCount | The ListCount property returns the number of items in the list. | Dim var As Long: var = CheckBoxCombo.ListCount |
| ListIndex | This property returns/sets the index of the currently focused/selected item in the list. | CheckBoxCombo.ListIndex = 5 'sets the focus to the item at index 5 Dim var As Long: var = CheckBoxCombo.ListIndex 'returns the index of the currently focused/selected item |
| NewIndex | This is a read-only property that returns the index of the item most recently added to CheckBoxCombo. | Dim var As Long: var = CheckBoxCombo.NewIndex 'returns index of the most recent item added |
| OnListSearch | The OnListSearch is a Get/Set property based on True or False. When the property is set to [Enabled], the user is allowed to type any text in the Editable Portion of the CheckBoxCombo, which is automatically searched on the list. The specialty of this search is the user can search for an item by any text part of it; no need to start from the beginning. This property is disabled by default. Note: If this property is enabled, it is easy to begin typing when the Edit Box of the CheckBoxCombo is focused and highlighted or just double-click on the Edit Box to clear it and then type. Once you find the item in the list, just click on it. |
CheckBoxCombo.OnListSearch = True |
| SelectAllOnRightClick | The SelectAllOnRightClick property determines select/unselect all items in the list, is allowed or not when the user right-click on the drop-down list. This is a Get/Set property based on True or False. The property is disabled by default. | CheckBoxCombo.SelectAllOnRightClick = True |
| Sorted | This is a Get/Set property used to sort the list items of CheckBoxCombo. The property has three options called [None, Alphabetical, InverseAlphabetical]. The option, [Alphabetical] sorts the list items in ascending order while the [InverseAlphabetical] sorts the list in descending order. The property is set to [None] by default. | CheckBoxCombo.Sorted = Alphabetical 'or CheckBoxCombo.Sorted = 1 |
| Selected | This property returns/sets selected status of a given item in the drop-down list. | CheckBoxCombo.Selected(1) = True 'select the item at Index 1 Dim var As Boolean: var = CheckBoxCombo.Selected(1) 'gets the selected status of item at Index 1 |
| SelItem | The SelItem is a read-only property that returns all the selected items in the list, seperated by the Delimiter. The SelItem property now supports an optional parameter of type Boolean called DelimiterConcatIncluded which is set to True by default. Note: If you have enabled the DelimiterConcat property, the SelItem property will contain the DelimiterConcat character concatenated with your original Delimiter. You can get the SelItem value excluding DelimiterConcat character by setting the DelimiterConcatIncluded to False. See the example and read the descriptions of (SelItemData, SelIndex, and Text) properties also. |
Dim var As String: var = CheckBoxCombo.SelItem 'gets all the selected items Dim var As String: var = CheckBoxCombo.SelItem(False) 'excludes DelimiterConcat character |
| SelItemData | The property is read-only and returns all the selected ItemData values in the list, seperated by the Delimiter. The SelItemData property now supports an optional parameter of type Boolean called DelimiterConcatIncluded which is set to True by default. Note: If you have enabled the DelimiterConcat property, the SelItemData property will contain the DelimiterConcat character concatenated with your original Delimiter. You can get the SelItemData value excluding DelimiterConcat character by setting the DelimiterConcatIncluded to False. See the example and read the descriptions of (SelItem, SelIndex, and Text) properties also. |
Dim var As String: var = CheckBoxCombo.SelItemData 'gets all the selected ItemData values Dim var As String: var = CheckBoxCombo.SelItemData(False) 'excludes DelimiterConcat character |
| SelIndex | This read-only property returns all the selected Indexes in the list, seperated by the Delimiter.The SelIndex property now supports an optional parameter of type Boolean called DelimiterConcatIncluded which is set to True by default. Note: If you have enabled the DelimiterConcat property, the SelIndex property will contain the DelimiterConcat character concatenated with your original Delimiter. You can get the SelIndex value excluding DelimiterConcat character by setting the DelimiterConcatIncluded to False. See the example and read the descriptions of (SelItem, SelItemData, and Text) properties also. |
Dim var As String: var = CheckBoxCombo.SelIndex 'gets all the selected Indexes Dim var As String: var = CheckBoxCombo.SelIndex(False) 'excludes DelimiterConcat character |
| SelCount | This property is read-only and returns the number of selected items in the list. | Dim var As Long: var = CheckBoxCombo.SelCount 'gets number of selected items |
| Method syntax | Description | Example of use |
|---|---|---|
| expression.AddItem(Item As String, [ItemData As Long], [Index As Long = -1], [Selected As Boolean = False]) As Long | This method adds/inserts an item to the CheckBoxCombo. The method takes four arguments. The [Item] parameter is required while the [ItemData], [Index] and [Selected] parameters are optional. The item is added to the list using the first argument. The second argument sets the ItemData value for the item being added. The third argement inserts the item at specific index. The forth argument select the list item being added/inserted. If the item is successfully added/inserted to the list, the method returns zero-based index, otherwise returns -1. | CheckBoxCombo.AddItem "Test", 1, 0, True 'add an item called "Test" with ItemData value 1 at index 0 and select it. |
| expression.RemoveItem(Index_or_Item As Variant) As Long | This method removes an item from the list by a given Index or the Item itself. If the method suceeds it returns the number of items in the list else returns -1. | CheckBoxCombo.RemoveItem 1 'removes an item at Index 1 CheckBoxCombo.RemoveItem "Japan" 'removes an item by the item itself CheckBoxCombo.RemoveItem "500" 'removes an numerical item, 500 from the list |
| expression.FindItem(Item As String, [Whole As Boolean = True]) As Long | This method checks for the availability of a given item in the drop-down list and returns the index of the item if found, otherwise returns -1. The method taks two arguments, where the first one is the item to be searched, which is required. The second argument determines whether an exact search of the item is needed. | Dim var As Boolean: var = CheckBoxCombo.FindItem("Sri Lanka") 'search for an exact item match |
| expression.List(Index As Long, [Item As String], [ItemData As Long]) As String | In traditional ComboBox, List is a property. However, CheckBoxCombo considers it as a method for more flexibility. This method returns/sets a list item of a given index. The method takes three arguments where the first one is required. The [Index] parameter determines the item to be accessed. The [Item] and/or [ItemData] sets the Item and/or ItemData value at the specified index. The method returns the item it accessed by the index given or a null string if failed. | Dim var As String: var = CheckBoxCombo.List(1) 'get the item at Index 1 CheckBoxCombo.List 5, "India", 6 'sets the item as "India" and ItemData as 6 for the item at index 5 |
| expression.Clear() | This method removes all the items from the list of CheckBoxCombo. | CheckBoxCombo.Clear 'removes all the items from the list |
| expression.SelectAll([Selected As Boolean = True]) | The method selects/unselects all the items in the list with its optional parameter, [Selected]. | CheckBoxCombo.SelectAll 'selects all items in the list CheckBoxCombo.SelectAll (False) 'unselects all items in the list |
| expression.SelectList(Selection As String, [SelectBy As SelectionType = Index], [Selected As Boolean = True]) | This method selects/unselects items in the list by the given Indexes or the Items itself. It supports three arguments. The [Selection] argument is required and it should contain the required indexes or the items itself seperated by the delimiter to select/unselect them in the list. The [SelectBy] argument determines the selection is done by the Index or the Item. The argument, [Selected] is optional and when it is set to False it unselect the items by the given indexes/items. In general, this method can be used to restore/discard any given selection by the indexes/items. (Useful in restoring after saving the selection) | CheckBoxCombo.SelectList("4,5,8") 'selects items in the list by the indexes 4, 5 and 8 CheckBoxCombo.SelectList("4,5,8", False) 'unselects items by the indexes 4, 5 and 8 CheckBoxCombo.SelectList("Japan,Brazil", Item, True) 'selects items by the items itself CheckBoxCombo.SelectList("Japan,Brazil", Item, False) 'unselects items by the items itself |
| expression.FillListByArray(DataSource As Variant, [ClearList As Boolean = False], [SortOrder As eSortOrder = 0]) | The FillListByArray method can be used to directly fill the list items of CheckBoxCombo through a String or Variant type array as its data source. The parameter
DataSource, which is required, should be the array containg Item, ItemData, Selected status each seperated by the Delimiter as an element. The method also supports two more optional parameters. The parameter [ClearList] determines that the list needs to be cleared before filling the items, while parameter, [SortOrder] determines that the list being filled, is to be sorted Alphabetical/InverseAlphabetical or not sorted. None of the optional parameters are applied by default. Note: The format of an element in the String/Variant type array should be one/more of the following.
|
Dim DS(2) As String DS(0) = "Item1" DS(1) = "Item2" DS(2) = "Item3"Call CheckBoxCombo.FillListByArray(DS, True, 1) 'clear and fill the list in ascending order You can add ItemData and Selected status also for an array element each seperated by the delimiter. Dim varDM as String varDM = CheckBoxCombo.Delimiter DS(0) = "Item1" & varDM & 0 & varDM & True |
| expression.FillListByRecordset(DataSource As Object, DisplayMember As String, [ValueMember As String = vbNullString], [SelectedMember As String = vbNullString], [ClearList As Boolean = False], [SortOrder As eSortOrder = 0]) | The FillListByRecordset method can be used to directly fill the list items of CheckBoxCombo through a Recordset (ADO/DAO) as its data source. The method supports six parameters. The [DataSource] paramether, which is required, takes its argument as a Recordset. The required [DisplayMember] paramether takes its argument as the field name in the Recordset to be used as the Items for the list. The [ValueMember], which is an optional parameter takes its argument as the field name in the Recordset to be used as the ItemData values for the list items. The [SelectedMember] parameter is optional and takes its argument as the field name in the Recordset to be used as the Checked State of list items. The optinal parameter [ClearList] determines that the list needs to be cleared before filling the items, while the optional parameter, [SortOrder] determines that the list being filled, is to be sorted Alphabetical/InverseAlphabetical or not sorted by the item. None of the [ClearList], [SortOrder] parameters are applied by default. Tip: Since this method supports a Recordset, which can be filled by an SQL query, together with its optional parameters and CheckBoxCombo's other built-in methods and properties, CheckBoxCombo has a greater flexibility in its application with database programming. |
{make an ADO-reference} Dim rstCBC As New Recordset Dim displaymember As String Dim valuemember As String Dim selectedmember As String Set rstCBC = "{datasource}" displaymembr = "{field for items}" valuemember = "{field for ItemData}" selectedmember = "{field for checked state}" Call CheckBoxCombo.FillListByRecordset(rstCBC, displaymember, valuemember, selectedmember, True, InverseAlphabetical) For more details in action, please study the Database Demo provided. |
| expression.DropDown | This method forces the list in the specified combo box to drop down on user request. | CheckBoxCombo.DropDown |
| expression.CloseUp | This method forces the list in the specified combo box to close up on user request. | CheckBoxCombo.CloseUp |
| Event | Description |
|---|---|
| ItemCheck | The ItemCheck event occurs when the user select/unselect an item from the drop-down list of CheckBoxCombo. |
| CBCUpdateCompleted | The CBCUpdateCompleted is a special event, introduced with the CBCUpdate property. The event occurs when the CBCUpdate property is set to True and can be used to return the selection state of CheckBoxCombo. |
| DropDown | This event occurs when the drop-down portion of the CheckBoxCombo is about to be shown. |
| CloseUp | This event occurs when the drop-down portion of the CheckBoxCombo has been closed. |
| KeyDown | This event occurs when the user presses a key while the CheckBoxCombo has the focus. |
| KeyPress | The KeyPress event occurs when the user presses and releases a key or key combination while the CheckBoxCombo has the focus. |
Pressing any keyboard keys of [F4, Up Arrow, Right Arrow, Down Arrow, Left Arrow] opens the drop-down list when the CheckBoxCombo is focused and pressing any of [Esc, F4] closes the drop-down list.
LICENSING:
Free for any commercial and non-commercial use with the copyright information and author credits.
DISCLAIMER OF USE:
The user must assume the entire risk of use. No support guaranteed.
For comments, suggestions or error reports you can reach me at the email address mentioned at the bottom.
| Copyright © 2018 PGBSoft. All rights reserved. |
| E-mail: pgbsoft@gmail.com |